/**
 * \file    debugging.h
 * \brief   Documentation: How to debug WOSH Framework
 ****************************************************************************
 * @author  Alessandro Polo
 * @version 0.8.499 $Id: debugging.h 2324 2010-04-22 18:02:17Z alex $
 ****************************************************************************/
/* Copyright (c) 2007-2010, WOSH - Wide Open Smart Home 
 * by Alessandro Polo - OpenSmartHome.com
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the OpenSmartHome.com WOSH nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY Alessandro Polo ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL Alessandro Polo BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ****************************************************************************/

/*! \page page_debug Debugging
 *
 * Here we present some useful hints to help you with debugging WOSH-based software and the middleware itself.
 *
 * \section page_debug_toc Table of Contents:
 *
 *  - \ref page_debug_overview
 *
 *  - \ref page_debug_log
 *
 *  - Software debug:
 *    - \ref page_debug_gdb
 *    - \ref page_debug_valgrind
 *    - \ref page_debug_libs
 *    - \ref page_debug_common
 *
 *  - \ref page_debug_profiling
 *  - \ref page_debug_deprecated
 *
 * WOSH is a multi-threaded application, actually based on QT (and pthreads), which widely uses dynamic memory,
 * custom RTTI model, dynamic (de)allocators, Meyer and Gamma singleton patterns.
 * These procedures and tools will help detecting errors.
 *
 * Referred tools are freely available on the Internet and included in most Linux distribution.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_debug_overview Overview
 *
 * WOSH should usually be compiled in DEBUG mode, this will also include
 * debug symbols that can make it easier to track bugs in applications and libraries.
 * However, on some platforms, building WOSH and its libraries in debug mode will cause
 * applications to be larger than desirable.
 *
 * It may be very hard to debug WOSH, some reasons are:
 *   - WOSH is a distributed system, running on more hosts/networks
 *   - WOSH is a service framework, many services (processes) are running at same time
 *   - WOSH is bus-oriented, saving the state of the system (or a service) is always transitional
 *   - WOSH is growing, you need to know source code tree, coding style and where things are placed
 *
 * Distributed Systems, unlike most centralized systems, fail only partially
 * and usually due to communication issues.
 * Within WOSH system, just a single service may crash, but worst case is a failure
 * of the Message dispatcher (like a deadlock because of bugs of a service's handler).
 *
 * However biggest problems are created and hopefully solved by framework developers, 
 * while you probably want to debug a single Bundle or few bundles cooperating.
 *
 * As you should know, there are many useful tools such as GDB, Valgrind on Linux,
 * the integrated Microsoft Visual Studio Debugger on Windows.
 *
 * WOSH provides some core-modules and components very useful for debugging and detecting problems:
 *
 *  - Logging
 *     - core components: wosh::LogContext represents a Log section; wosh::LogHandler writes log entries to final output (such as a file, stderr)
 *     - wosh::DefaultSharedLogHandler (meyer singleton) writes log (optionally) to file(s) and stderr
 *     - generic function handler \ref log() using default handler
 *     - module: wosh::SystemLogger (runtime listing/editing of registered log contexts/handlers)
 *
 *  - Monitoring
 *     - module: wosh::ThreadManager (collects and monitors threads, may also detect crashes, meyer singleton)
 *     - module: wosh::SystemMonitor (maintains a cache of system-errors raised by the system)
 *     - core component: wosh::SystemError represent a generic system-error
 *
 *  - Profiling [*may be disabled while building WOSH]
 *     - core component: wosh::SystemProfiler (profiling manager, meyer singleton)
 *     - module: wosh::SystemMonitor (supports runtime read-only access to profiling information)
 *     - Profiling is available for following objects only: wosh::Property, wosh::Method, wosh::BusConnector. They are transparently monitored.
 *
 *  - Deprecated [*part of Profiling, it must be enabled]
 *     - core component: wosh::SystemProfiler (deprecated-list manager, meyer singleton)
 *     - module: wosh::SystemMonitor (supports runtime read-only access to deprecated method list)
 *     - Deprecated functions are defined by a simple macro and evaluated at run-time.
 *
 * It may be really hard to understand and recognize the process and the flow
 * which caused a failure, because of that WOSH comes with wosh::ThreadManager
 * and its component wosh::ThreadMonitor, which iterates the processes' status
 * recording and notifying possible crashes.
 *
 * The most common approach on a generic error is checking out WOSH logs, but
 * they are often very verbose, wosh::SystemMonitor monitors and caches most
 * important (critical) and informative errors for you, this information is often 
 * enough to recognize the problem (such a missing/misconfigured Bundle and so on).
 *
 * Optimizing and evaluating performance of such distributed system is potentially
 * very complex and requires a deep knowledge of the architecture.
 * However there are some shared low-level components, which are intrinsically
 * a bottle-neck and when misused might cause slowdowns or even deadlocks.
 * WOSH provides an optional, fully transparent, profiling system for Properties,
 * Methods, and Bus-connections.
 *
 * WOSH is still in development stage: because of that there may be some old,
 * deprecated functionalities which are still available, but are (will be)
 * replaced or removed. This information is defined within code and it is
 * evaluated (and registered) at run-time. It may be helpful to avoid
 * headaches caused by missing/out-of-date implementation or underlying components.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_debug_log WOSH Logging
 *
 * \note Logging-system has been totally rewritten in WOSH 0.8.013 [icarus]
 *
 * Logging is the easiest way to detect and understand issues for end-users and developer both.
 *
 * Information about logging system and its architecture are available in \ref page_core_systemlogger page,
 * this section covers log-analisys and generic notes only.
 *
 * \ref page_applications write log-files to <a href="../../var/log">/var/log</a> by default,
 * log filename refers to the application binary.
 * Depending on configuration and implementation, the application may write a single file (appending)
 * or multiple files (size-check, log-rotation).
 *
 * \ref page_applications_woshsrv "WOSH Server" prints logs on stderr by default,
 * entries are coloured (on POSIX and Windows both) to empathize severity.
 *
 * Some sample log-files are provided with full distribution:
 *  - <a href="../../var/log/sample.woshsrv.log">/var/log/sample.woshsrv.log</a>
 *  - <a href="../../var/log/sample.woshshop.log">/var/log/sample.woshshop.log</a>
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_debug_gdb GNU Debugger (GDB)
 *
 * GDB, the GNU Project debugger, allows you to see what is going on 'inside' another
 * program while it executes -- or what another program was doing at the moment it crashed. 
 *
 * To run \c gdb, just execute:
 * \verbatim
alex@linbox:/home/alex/WOSH/bin$ gdb ./woshsrv
\endverbatim
 * Then, execute \c run command to start the program.
 *
 * To stop the application:
 *   - press CTRL-C to get gdb console
 *   - execute 'signal 2' (to send a CTRL-C to the application itself)
 *
 * To exit debugger, run \c quit. very useful command is \c backtrace.
 *
 * \see http://www.gnu.org/software/gdb/
 *
 * On Linux Debian-based systems you may install \c GDB executing:
 * \verbatim
alex@linbox:/$ sudo apt-get install gdb
\endverbatim
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_debug_valgrind Valgrind
 *
 * valgrind (http://www.valgrind.org/) is a Linux tool for finding memory access errors to heap memory
 * (memory that is dynamically allocated with new or malloc) in C and C++ programs.
 * Memory access errors are the most difficult bugs to find and to fix.
 * The types of errors it can find include memory leaks, reading un-initialized memory,
 * accessing unallocated memory, and array out-of-bounds errors.
 *
 * Running valgrind is easy. Just compile your program with \c -g, then run the executable, for example:
 * \verbatim
alex@linbox:/home/alex/WOSH/bin$ valgrind --leak-check=full --show-reachable=yes --log-file=valgrind.log  ./woshsrv
\endverbatim
 * You may leave out '--show-reachable=yes' flag to reduce provided information.
 *
 * The program will run much slower (eg. 20 to 30 times) than normal, and use a lot more memory.
 * Note that some (warning/errors) are inherited by QT Libraries and may be ignored safely.
 *
 * \see http://valgrind.org
 * \see http://valgrind.org/docs/manual/cl-manual.html
 * \see http://valgrind.org/docs/manual/ms-manual.html
 *
 * On Linux Debian-based systems you may install \c valgrind executing:
 * \verbatim
alex@linbox:/$ sudo apt-get install valgrind
\endverbatim
 * 
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_debug_libs Shared Libraries
 *
 * The shared library dependencies of the executable can be listed with the POSIX command: \c ldd name-of-executable
 * \verbatim
alex@linbox:/home/alex/WOSH/bin$ ldd woshsrv
\endverbatim
 * A sample output is provided (<a href="../../var/log/dependences.woshsrv.posix.ldd">/var/log/dependences.woshsrv.posix.ldd</a>):
 *
 * WOSH Core and Framework is based on STL and QT library. However built-in bundles
 * may link against some custom libraries, previous ldd-output sample lists many
 * libraries which are not really required by WOSH Core. Same assumption is valid on Windows.
 *
 * On POSIX, the command \c nm lists symbols contained in the object file or shared library. 
 * 
 * On Windows you may use \c "Dependency Walker" software to identify required libraries, output files are included in source distribution:
 *  - <a href="../../var/log/dependences.woshsrv.win32.txt">/var/log/dependences.woshsrv.win32.txt</a>
 *  - <a href="../../var/log/dependences.woshshop.win32.txt">/var/log/dependences.woshshop.win32.txt</a>
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_debug_common Common problems
 *
 * Here are listed most common problems encountered by developers when building the system.
 *
 *  - [..] inherits [..] via dominance
 *    \c Problem: missing WOSH_CLASSNAME(), WOSH_CLASS_ABSTRACT() macro call (defined in Reflection.h)
 *    \c Solution: insert the WOSH macros \b just \b after class definition, before anything else; when
 *    inheriting a QT::QObject, it's a good practice to place QOBJECT macro \b before any WOSH macros.
 *
 *  - [..] : ambiguous inheritance of [..] (no unique final overrider)
 *    \c Problem: may happen when you implement more interfaces in same class, due to diamond inheritance (well known) problem,
 *    \c Solution: you must define highest implemented interface, you probably forgot the MACRO definition
 *
 *  - Your new type is not listed in the RTTI tree or can't be allocated.
 *    \c Problem: \b missing/misused WOSH_REGISTER() or WOSH_REGISTER_INTERFACE() (defined in ObjectAllocator.h)
 *    \c Solution: add/rewrite the definition in the \c cpp file, be aware on version information (set it to 0.0 if you don't care about versioning)
 *
 *  - Errors at \c WOSH_REGISTER or \c WOSH_REGISTER_INTERFACE (such as: redefinition; multiple initialization)
 *    \c Problem: redefined WOSH_REGISTER() or WOSH_REGISTER_INTERFACE() (defined in ObjectAllocator.h)
 *    \c Solution: define it only \b once in a CPP file (do NOT write this macro in header files!), last argument
 *    must be any \b unique literal name.
 *
 *  - Errors at \c WOSH_REGISTER or \c WOSH_REGISTER_INTERFACE (such as: syntax error : 'string')
 *    \c Problem: MACRO is not defined
 *    \c Solution: #include <core/ObjectAllocator.h>
 *
 * \par Common compilation problems inherited by QT:
 *  There is one bug that is so common that it deserves mention here:
 *  If you include the \c Q_OBJECT macro in a class declaration and run the meta-object compiler (moc),
 *  but forget to link the moc-generated object code into your executable,
 *  you will get very confusing error messages. Any link error complaining about a lack of \c vtbl,
 *  \c _vtbl, \c __vtbl or similar is likely to be a result of this problem.
 *
 *
 ****************************************************************************
 *
 */

